home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / shsein.z / shsein
Encoding:
Text File  |  2002-10-03  |  9.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SHSEIN - use inverse iteration to find specified right and/or left
  10.      eigenvectors of a real upper Hessenberg matrix H
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE SHSEIN( SIDE, EIGSRC, INITV, SELECT, N, H, LDH, WR, WI, VL,
  14.                         LDVL, VR, LDVR, MM, M, WORK, IFAILL, IFAILR, INFO )
  15.  
  16.          CHARACTER      EIGSRC, INITV, SIDE
  17.  
  18.          INTEGER        INFO, LDH, LDVL, LDVR, M, MM, N
  19.  
  20.          LOGICAL        SELECT( * )
  21.  
  22.          INTEGER        IFAILL( * ), IFAILR( * )
  23.  
  24.          REAL           H( LDH, * ), VL( LDVL, * ), VR( LDVR, * ), WI( * ),
  25.                         WORK( * ), WR( * )
  26.  
  27. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  28.      These routines are part of the SCSL Scientific Library and can be loaded
  29.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  30.      directs the linker to use the multi-processor version of the library.
  31.  
  32.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  33.      4 bytes (32 bits). Another version of SCSL is available in which integers
  34.      are 8 bytes (64 bits).  This version allows the user access to larger
  35.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  36.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  37.      only one of the two versions; 4-byte integer and 8-byte integer library
  38.      calls cannot be mixed.
  39.  
  40. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  41.      SHSEIN uses inverse iteration to find specified right and/or left
  42.      eigenvectors of a real upper Hessenberg matrix H. The right eigenvector x
  43.      and the left eigenvector y of the matrix H corresponding to an eigenvalue
  44.      w are defined by:
  45.  
  46.                   H * x = w * x,     y**h * H = w * y**h
  47.  
  48.      where y**h denotes the conjugate transpose of the vector y.
  49.  
  50.  
  51. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  52.      SIDE    (input) CHARACTER*1
  53.              = 'R': compute right eigenvectors only;
  54.              = 'L': compute left eigenvectors only;
  55.              = 'B': compute both right and left eigenvectors.
  56.  
  57.      EIGSRC  (input) CHARACTER*1
  58.              Specifies the source of eigenvalues supplied in (WR,WI):
  59.              = 'Q': the eigenvalues were found using SHSEQR; thus, if H has
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  71.  
  72.  
  73.  
  74.              zero subdiagonal elements, and so is block-triangular, then the
  75.              j-th eigenvalue can be assumed to be an eigenvalue of the block
  76.              containing the j-th row/column.  This property allows SHSEIN to
  77.              perform inverse iteration on just one diagonal block.  = 'N': no
  78.              assumptions are made on the correspondence between eigenvalues
  79.              and diagonal blocks.  In this case, SHSEIN must always perform
  80.              inverse iteration using the whole matrix H.
  81.  
  82.      INITV   (input) CHARACTER*1
  83.              = 'N': no initial vectors are supplied;
  84.              = 'U': user-supplied initial vectors are stored in the arrays VL
  85.              and/or VR.
  86.  
  87.      SELECT  (input/output) LOGICAL array, dimension (N)
  88.              Specifies the eigenvectors to be computed. To select the real
  89.              eigenvector corresponding to a real eigenvalue WR(j), SELECT(j)
  90.              must be set to .TRUE.. To select the complex eigenvector
  91.              corresponding to a complex eigenvalue (WR(j),WI(j)), with complex
  92.              conjugate (WR(j+1),WI(j+1)), either SELECT(j) or SELECT(j+1) or
  93.              both must be set to
  94.  
  95.      N       (input) INTEGER
  96.              The order of the matrix H.  N >= 0.
  97.  
  98.      H       (input) REAL array, dimension (LDH,N)
  99.              The upper Hessenberg matrix H.
  100.  
  101.      LDH     (input) INTEGER
  102.              The leading dimension of the array H.  LDH >= max(1,N).
  103.  
  104.      WR      (input/output) REAL array, dimension (N)
  105.              WI      (input) REAL array, dimension (N) On entry, the real and
  106.              imaginary parts of the eigenvalues of H; a complex conjugate pair
  107.              of eigenvalues must be stored in consecutive elements of WR and
  108.              WI.  On exit, WR may have been altered since close eigenvalues
  109.              are perturbed slightly in searching for independent eigenvectors.
  110.  
  111.      VL      (input/output) REAL array, dimension (LDVL,MM)
  112.              On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL must contain
  113.              starting vectors for the inverse iteration for the left
  114.              eigenvectors; the starting vector for each eigenvector must be in
  115.              the same column(s) in which the eigenvector will be stored.  On
  116.              exit, if SIDE = 'L' or 'B', the left eigenvectors specified by
  117.              SELECT will be stored consecutively in the columns of VL, in the
  118.              same order as their eigenvalues. A complex eigenvector
  119.              corresponding to a complex eigenvalue is stored in two
  120.              consecutive columns, the first holding the real part and the
  121.              second the imaginary part.  If SIDE = 'R', VL is not referenced.
  122.  
  123.      LDVL    (input) INTEGER
  124.              The leading dimension of the array VL.  LDVL >= max(1,N) if SIDE
  125.              = 'L' or 'B'; LDVL >= 1 otherwise.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      VR      (input/output) REAL array, dimension (LDVR,MM)
  141.              On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR must contain
  142.              starting vectors for the inverse iteration for the right
  143.              eigenvectors; the starting vector for each eigenvector must be in
  144.              the same column(s) in which the eigenvector will be stored.  On
  145.              exit, if SIDE = 'R' or 'B', the right eigenvectors specified by
  146.              SELECT will be stored consecutively in the columns of VR, in the
  147.              same order as their eigenvalues. A complex eigenvector
  148.              corresponding to a complex eigenvalue is stored in two
  149.              consecutive columns, the first holding the real part and the
  150.              second the imaginary part.  If SIDE = 'L', VR is not referenced.
  151.  
  152.      LDVR    (input) INTEGER
  153.              The leading dimension of the array VR.  LDVR >= max(1,N) if SIDE
  154.              = 'R' or 'B'; LDVR >= 1 otherwise.
  155.  
  156.      MM      (input) INTEGER
  157.              The number of columns in the arrays VL and/or VR. MM >= M.
  158.  
  159.      M       (output) INTEGER
  160.              The number of columns in the arrays VL and/or VR required to
  161.              store the eigenvectors; each selected real eigenvector occupies
  162.              one column and each selected complex eigenvector occupies two
  163.              columns.
  164.  
  165.      WORK    (workspace) REAL array, dimension ((N+2)*N)
  166.  
  167.      IFAILL  (output) INTEGER array, dimension (MM)
  168.              If SIDE = 'L' or 'B', IFAILL(i) = j > 0 if the left eigenvector
  169.              in the i-th column of VL (corresponding to the eigenvalue w(j))
  170.              failed to converge; IFAILL(i) = 0 if the eigenvector converged
  171.              satisfactorily. If the i-th and (i+1)th columns of VL hold a
  172.              complex eigenvector, then IFAILL(i) and IFAILL(i+1) are set to
  173.              the same value.  If SIDE = 'R', IFAILL is not referenced.
  174.  
  175.      IFAILR  (output) INTEGER array, dimension (MM)
  176.              If SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right eigenvector
  177.              in the i-th column of VR (corresponding to the eigenvalue w(j))
  178.              failed to converge; IFAILR(i) = 0 if the eigenvector converged
  179.              satisfactorily. If the i-th and (i+1)th columns of VR hold a
  180.              complex eigenvector, then IFAILR(i) and IFAILR(i+1) are set to
  181.              the same value.  If SIDE = 'L', IFAILR is not referenced.
  182.  
  183.      INFO    (output) INTEGER
  184.              = 0:  successful exit
  185.              < 0:  if INFO = -i, the i-th argument had an illegal value
  186.              > 0:  if INFO = i, i is the number of eigenvectors which failed
  187.              to converge; see IFAILL and IFAILR for further details.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))                                                          SSSSHHHHSSSSEEEEIIIINNNN((((3333SSSS))))
  203.  
  204.  
  205.  
  206. FURTHER DETAILS
  207.      Each eigenvector is normalized so that the element of largest magnitude
  208.      has magnitude 1; here the magnitude of a complex number (x,y) is taken to
  209.      be |x|+|y|.
  210.  
  211.  
  212. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  213.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  214.  
  215.      This man page is available only online.
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.